Almathera Ten Pack 2: CDPD 1/Almathera Ten on Ten - Disc 2: CDPD 1.iso/pd/076-100/077/quest/quest.doc

Text File | 1995-03-13 | 17KB | 356 lines

                Quest


     Four files are included in Quest. Three provide independent
libraries of useful utilities which are the framework of any Quest
scenario. The fourth is a simple sample scenario. The sample scenario
doesn't do anything, but does illustrate the use of the rest of the
system, and provides a working demo of most of the facilities.


qcrt.d - CRT routines.

     These routines handle a 24 line by 80 column screen. Even though the sizes
are parameterized as constants (NLINES and NCOLUMNS), it is not likely that the
code would work properly with a different size screen. All routines whose names
begin with 'CRT_' are in my CRT library. The routines used are:

    CRT_Initialize(*char title; ushort nLines, nCols) - open a window
    of given size and set its title
    CRT_Terminate() - closes the window
    CRT_ClearScreen() - clear the screen & leave cursor at (0, 0)
    CRT_ClearLine(ushort line) - clear line & leave cursor at (line, 0)
    CRT_Abort() - close window and return to system cleanly
    CRT_Move(ushort line, column) - move the cursor to the indicated
    (0-origin) line and column on the screen
    CRT_EnterHighLight() - output after this will be highlighted, e.g.
    in a different color
    CRT_ExitHighLight() - output after this will be normal
    CRT_ClearTail() - the current line from the cursor to the last
    column is cleared - the cursor is not moved
    CRT_ClearToEnd(ushort line) - the cursor is moved to the beginning
    of the given line and the screen is cleared from there on down
    CRT_PutChars(*char string) - the given string is output to the
    screen at the current cursor position
    CRT_PutChar(char ch) - the character is output to the screen
    CRT_ReadChar()char - wait for and read a character from the terminal
    CRT_GetLine(*char buffer; ushort length) - this routine reads an
    input line of the given maximum length into the buffer. Input
    line editing (backspace, line delete) is enabled.

     The upper left-hand corner of the screen, 11 lines by 38 columns, is
used to display an 11 line by 19 column region of a "scenery map" which
is a sort of bird's eye view of the region around the player character
(PC) or group. Each 'cell' in the map is represented by two characters,
side by side. The CRT routines maintain this view by calling a user-
supplied scenery generator, which, given the line and column
co-ordinate, returns the pair of characters to display for that position.
Also maintained is a list of 'movable objects' which are not considered
part of the scenery. Each has a pair of characters to display. They are
displayed 'over top of' the scenery, and the last such specified at a
given position is the one displayed. Each has an identifier by which the
user programmer can refer to it. The one with identifier = 0 is assumed
to be the PC or group, and if it is moved to or off of the edge of the
viewing area, then the entire map view is windowed (which will entail a
number of calls to the user-supplied scenery generator).

     The upper right-hand corner of the screen, 11 lines by 40 columns,
is used to display various status indicators needed by the scenario.
There are three kinds of status indicators: numeric, string and string-
list. These are set up by calling the appropriate routine with a numeric
identifier for the item, it's header string, it's position in the status
area (line, column of the first character of the header), and the item's
size. These routines are also passed the address of the actual variable
which records the current value, so that a simple call to 'scUpdate' can
update the status display directly. String-list items are used for
things such as the list of things the PC is carrying - the update
routine handles correct formatting for multi-line display with
separating commas. Instead of being given the address of the list
header, the 'scMult' routine is passed a procedure which it is to call
to get successive strings to display.

     The bottom 12 lines of the screen are used for text input/output as
occurs in most Adventure style games. When the bottom of the screen is
reached, the area is cleared and I/O continues on the first line of the
region. If the bottom is reached during output, then the output pauses
until the end-user types a key to continue (my version displays 'MORE',
highlighted, down the right-hand edge of the region). The output routine
handles one character at a time. This allows me to use it as a Draco
text output channel through which I can 'write' or 'writeln' whatever I
need to output. Output in this way will automatically do word breaks at
the correct place. (This means that, unless special output formats are
needed, text can be output in one big continuous stream, and will be
automagically broken on word boundaries.)

     All CRT routines have names beginning with 'sc'. They are:

Miscellaneous routines:

scInit() - this must be called once before any other calls.

scTerm() - called to free up resources used by CRT routines. This
    also calls CRT_Terminate to terminate the entire program.

Map area routines:

scNewMap(proc(long line, column)[2]char scenery; *byte oldObj)*byte -
    this fancy header indicates that 'scNewMap' has 2 parameters and
    returns a result. The first parameter is a procedure which takes two
    long integer parameters and returns an array of 2 characters - this
    is the scenery generator mentioned above. The second parameter is
    the list of "movable objects" associated with the map. This is
    usually just 0, but is used when a scenario involves more than one
    map (it preserves the "movable objects" between uses of the map).
    The value returned is the "movable objects" list that used to be
    active. This routine must be called before the map area is used for
    anything.

scObjFree(*byte ol) - free any object list left behind from other map
    areas by calls to scNewMap. The list currently active is freed by
    scTerm.

scWindow(long line, column) - forces the map area to be redrawn, centered
    on the given co-ordinates.

scNew(Id_t id; long line, column; [2]char chars) - this routine is used
    to create a new "movable object". The id is used to refer to the
    entry when moving or deleting it. The line and column are where the
    object is now, and the two characters are what to display for it.

scAt(long line column)[2]char - return the pair of characters which is
    currently displayed at the given position.

scMove(Id_t id; long line, column) - the specified "movable object" is
    moved to the given location and redisplayed (if within the window).

scDelete(Id_t id) - the specified "movable object" is removed and can
    no longer be referenced.

Status area routines:

scNumber(Id_t id; *char name; ushort line, column, length; *long ptr) -
    this routine is used to create a numeric status display. 'name' is
    the string to use for a header, 'line' and 'column' specify where in
    the status area to display the item, 'length' is the number of
    spaces to use for the numeric display (format is 'HEADER: xxxx'),
    and ptr is the address of the variable which is being displayed. (
    This address is saved away so that calls to 'scUpdate' can cause a
    re-display without having to pass in the new value.)

scString(*d_t id; *char name; ushort line, column, length; **char ptr) -
    this routine is used to create a string status display. 'length' is
    the length of the string to be used (it will be padded on the right
    or truncated as needed). 'ptr' points to the string variable.

scMult(Id_t id; *char name; ushort line, column, lines;
       proc(bool first)*char gen) - this routine is used to create a
    string-list status display. 'lines' is the number of lines reserved
    for this item (successive lines start in the 3rd column of the
    status display area). 'gen' is a procedure to call to get the items
    to be displayed in the list. It has a parameter telling it to start
    over since, if the items won't fit in the available space, the
    display process will prematurely stop calling it. If the items won't
    fit in the available lines, the last one is followed by '..' to
    indicate that there were more items.

scUpdate(Id_t id) - the specified status item is re-displayed. Once the
    display items are set up, this is the only display item routine that
    will be needed.

Text I/O routines:

scPut(char ch) - this routine is called to output a character in the
    text area. Word break and pagination is handled as discussed above.
    The character '\n' (linefeed) are used to signal the need for a
    forced newline.

scPrompt(*char prompt) - this routine is called to specify the prompt to
    use on input.

scRead(*char buffer) - an input line is read into the passed buffer. If
    any text was left to be output (it is buffered up to allow for the
    word-break processing) it is output first and a new line started.
    Any prompt is output before the read is done.


qparse.d - the parser.

     The parser is fairly simple but will handle a variety of input
styles, ranging from the simple 'get book' to the more complex 'Put the
magic sword into the glass trophy case.' No provisions are currently
present for having multiple commands on one line unless the grammar
specifies it directly (quite cumbersome). Prefixes, consisting of words
before an initial ':' can be picked off, but this facility will probably
not be used (see later). These routines handle the dictionary, which
contains words, along with their id (should be unique) and type (the
parser places no interpretation on types, but they are needed). The
words are stored directly as given (any characters can be used), but
when the parsing occurs, case will be ignored. Also, when parsing,
spaces are used as word separators, so having 'words' with spaces in
them will not work.

     The grammar parsed consists of a number of sentence forms, each of
which is simply a list of elements. An element can be a specific word
which is required, a specific word-type which is required, an optional
specific word, an optional word-type or a sequence of words of a given
type. For example, the grammar sentence

    give [ARTICLE] ADJECTIVE* NOUN to [ARTICLE] ADJECTIVE* NOUN
    [PUNCTUATION]

could be used to handle the verb 'give'. Input sentences like

    Give the big red rose to the ugly dwarf.
    give sword to troll

would be accepted (provided the words were in the dictionary and had
been flagged with the appropriate types). The various sentence forms are
tried one at a time to match the input commands, thus the ones given
first will take precedence over later ones in case of ambiguity.

    All parser routine names start with 'ps'. They are:

psInit(bool prefixEnabled) - must be called once before any other parser
    routines are used. If 'prefixEnabled' is true, then prefixes ending
    with ':' will be picked off of input sentences, otherwise they are
    handled as part of the input sentence. Even when such prefixes are
    used (e.g. to talk to NPC's), it is probably better to have separate
    grammar rules for the things that can be said to NPC's, instead of
    having these things mixed in with the rules for direct commands. The
    whole area needs more thought.

psTerm() - called at the end of the run to free up space used by the
    stored dictionary and grammar, and any working storage used by the
    parser.

psWord(Id_t id; *char txt; Id_t typ) - the given word is added to the
    dictionary with the given id and word-type. More than one entry with
    the same id can be added - they are synonyms. Punctuation 'words'
    are added in the same way.

psDel(Id_t id) - called to delete the specified word from the
    dictionary.

psgBegin(Id_t id) - called to start the specification of a grammar
    rule with the given id.

psgWord(PSForm_t form; Id_t data) - called to add an element to a grammar
    rule. PSForm_t is an enumeration type with values f_reqId,
    f_reqType, f_optId, f_optType, and f_multiple which is included in
    q.g. The five element types were discussed above (required word of
    given id, required word of given type, optional word of given id,
    optional word of given type, multiple words of given type). The
    'data' parameter is either the id or word-type, as needed.

psgEnd() - called to signal the end of a grammar rule. Grammar rules can
    be added at any time, as can dictionary entries; thus the language
    can grow as the game progresses.

psgDel(Id_t id) - delete the specified grammar rule from the grammar.

psFind(*char txt)Id_t - looks a word up in the dictionary. Returns the
    id of the word, or 0 if the word isn't found (thus id = 0 should not
    be used for any word).

psType(Id_t id)Id_t - returns the word-type of the identified word

psGet(Id_t id)*char - returns the text of the identified word

psParse(*char sentence)Id_t - this routine parses the given input string
    according to the currently existing dictionary and grammar rules. It
    returns: PS_ERROR if some word in the input is unknown (call pspBad
    to get the text of the word); PS_BAD if all words were known but the
    input didn't match any of the grammar rules; else the grammar rule
    number of the matched rule For a successful match, 'pspWord' and
    'pspPref' can be used to find more details.

pspBad()*char - called after pspParse has returned PS_ERROR to get the
    text of the word which wasn't in the dictionary. (The parser stops
    as soon as it finds one, so there will only be the one.)

pspWord(uint pos)Id_t - returns the id of the word(s) that matched the
    'pos'th position in the successful grammar rule. For optional
    elements, 0 is returned if no word was there. For multiple elements,
    successive calls to 'pspWord' with the same 'pos' will return the
    various words that matched. No more (or none at all) is signalled by
    'pspWord' returning 0.

pspPref()Id_t - After psParse when prefixes are enabled, successive calls
    to this routine will return the id's of the words that were part of
    the prefix (the stuff before the first ':'). To handle prefixes like
    'Dan, Joe:', comma should be made a word and will be dutifully
    returned by pspPref. (The ':' is thrown away.) pspPref returns 0
    when there are no more prefix words (if there were any at all).


qlist.d - list handling routines.

     These routines are used for handling semantic information. They
care nothing about meanings - they are just general tools. One set of
routines (names start with 'l') simply handles lists of integers (
adding, appending, deleting, etc.) Another set handles properties (
essentially arbitrary boolean (true/false) flags) associated with
identifiers. A third set handles attribute-value pairs associated with
identifiers (things like (size 2), (weight 20), (color red), etc.).

lInit() - this routine must be called before any others in this set.

lFree(*List_t il) - called to free a list for the user program.

lTerm() - called to free up all list structures at end of run.

getId()Id_t - called to get a unique integer id. The values returned on
    consecutive calls are just 1, 2, 3, etc. Note that this routine was
    never used in the sample scenario program, since all id's were
    needed to be known in several places.

Simple list handling routines.

Type List_t given in q.g defines the elements of the lists. A list
variable is of type *List_t.

lAdd(**List_t pil; Id_t n) - the value 'n' is added to the front of the
    list. No check is made to see if it is already in the list.

lAppend(**List_t pil; Id_t n) - the value 'n' is appended to the end of
    the list. No check is made to see if it is already in the list.

lDelete(**List_t pil; Id_t n) - the first occurrence (if any) of the
    value 'n' is deleted from the list.

lGet(*List_t il; ulong n)Id_t - the value of the n'th element of the list
    is returned (if any, else 0).

lIn(*List_t il; Id_t n)bool - returns 'true' if the value 'n' is in the
    list, else returns 'false'.

Property handling routines.

putProp(Id_t id, prop) - associates property 'prop' with item 'id'.

getProp(Id_t id, prop)bool - returns 'true' if property 'prop' is
    associated with item 'id', else returns 'false'.

delProp(Id_t id, prop) - ensures that property 'prop' is not associated
    with item 'id'.

Attribute-value handling routines.

putAttr(Id_t id, attr, val) - associates attribute 'attr' with value
    'val' with item 'id'. Any previous association is replaced.

getAttr(Id_t id, attr)Id_t - returns the value for attribute 'attr'
    associated with item 'id', else 0 if none.

delAttr(Id_t id, attr) - dissassociates attribute 'attr' from item 'id'.


qmain.d - sample scenario.

     If you are going to study any of the Quest source files, it should
be this one. Writing a scenario does not require studying of the others,
but this one is a must. I won't describe here what it does, but instead
refer you to the comments in the file itself. You may have to refer back
to the above descriptions, so you'll probably want to load the two files
into an editor and read them that way.